home *** CD-ROM | disk | FTP | other *** search
/ Aminet 38 / Aminet 38 (2000)(Schatztruhe)[!][Aug 2000].iso / Aminet / gfx / pbm / netpbmwos.lha / netpbm / Netpbm.programming < prev    next >
Text File  |  2000-05-29  |  4KB  |  95 lines
  1. This file is an attempt to give some basic guidelines for those who
  2. wish to write new Netpbm programs.  The guidelines ensure:
  3.  
  4.   A) Your program functions consistently with the rest of the package.
  5.  
  6.   B) Your program works in myriad environments on which you can't test it.
  7.  
  8.   C) You don't miss an important details of the Netpbm formats.
  9.  
  10.   D) Your program is immune to small changes in the Nepbm formats.
  11.  
  12. The easiest way to write your own facility, is to take an existing
  13. one, similar to the one you want to write, and to modify it. This
  14. saves a lot of time, and ensures conformity with these rules.
  15.  
  16. The Netpbm maintainer accepts programs that do not meet these guidelines,
  17. so don't feel you need to hold back a contribution because you wrote it
  18. before you read these.
  19.  
  20. * See the libp?m.3 man pages for documentation of the various library
  21.   routines you should use to read and write Netpbm images and perform
  22.   other common operations.  
  23.  
  24. * See the p?m.5 man pages for specifications of the Netpbm formats, but
  25.   don't depend very much on these; use the library functions instead to
  26.   read and write the image files.
  27.  
  28. * Your new program must belong to one of the four Netpbm formats,
  29.   i.e. pbm, pgm, ppm or pnm. They are defined as follows:
  30.  
  31.   pbm: Bitmaps only, i.e. a pixel is either black or white.
  32.  
  33.   pgm: Gray scales, i.e. a pixel can have any value between black
  34.        and white, but no colours.
  35.  
  36.   ppm: Colour images. Note that Netpbm does not support the use of
  37.        look up tables.
  38.  
  39.   pnm: A facility able to create or read more than one of the formats
  40.        above. Note that all pgm programs can automatically read pbm
  41.        images, and that all ppm programs can automatically read both
  42.        pbm and pgm files. A pnm utility does more than this, its action
  43.        depends on the type of the input file. E.g. the pnmtotiff utility
  44.        creates a bitmap TIFF file when it reads a pbm file on its input,
  45.        a gray scale TIFF files when it reads a pgm file on its input, etc.
  46.        ppmtogif on the other hand treats a pbm file on its input exactly
  47.        as if it were a ppm file with only the colours black and white.
  48.  
  49.   Decide which one of these formats your program belongs to.
  50.  
  51. * If you want to use global variables or global functions in your program,
  52.   make them static, so that they won't cause problems to other programs
  53.   when you compile a merged binary (see the Makefile).
  54.  
  55. * Declare main as: int main(argc, argv), not void! Some systems won't
  56.   compile void main().
  57.  
  58. * Always start the code in main() with a call to p?m_init().
  59.  
  60. * Use pm_error() and pm_message() for error messages and other messages.
  61.  
  62. * Don't forget to write a proper manual page!
  63.  
  64. * Properly use maxvals.  As explained in the format specifications, every
  65.   sample value in an image must be interpreted relative to the image's
  66.   maxval.  For example, a pixel with value 24 in an image with maxval 24
  67.   is the same brightness as a pixelwith value 255 in an image with a
  68.   maxval of 255.
  69.  
  70.   255 is a popular maxval (use the PPM_MAXMAXVAL etc. macros) because it
  71.   makes samples fit in a single byte and at one time was the maximum 
  72.   possible maxval in the format.
  73.  
  74.   Note that the Pnmdepth program converts an image from one maxval to
  75.   another.
  76.  
  77. * Don't include extra function.  If you can already do something by 
  78.   piping the input or output of your program through another Netpbm
  79.   program, don't make an option on your program to do it.  That's the
  80.   Netpbm philosophy -- simple building blocks.
  81.  
  82.   Similarly, if your program does two things which would be useful
  83.   separately, write two programs and advise users to pipe them
  84.   together.
  85.  
  86. * Your program should, if appropriate, allow the user to use Standard
  87.   Input and Output for images.  This is because Netpbm users commonly
  88.   use pipes.
  89.  
  90. * Contrary to what you see in the old programs you may use as an
  91.   example, you may use just ANSI C and POSIX C library functions.  All
  92.   modern Netpbm users use those.  Look at the HISTORY file and find a
  93.   recent addition to Netpbm to use as an example.
  94.  
  95.